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Introduction 

Purpose 

This document describes the various features available within IBM Cognos Active 
Report and how they can be used to create and distribute interactive reporting 
applications. 

This document assumes a basic knowledge of IBM Cognos Active Report 
functionality. For introductory information please refer to the IBM Cognos Active 
Report section of the IBM Cognos Report Studio User Guide located under the 
Author and Create folder at 

http://publib.boulder.ibm.com/infocenter/cbi/v10r1 ml/index.jsp or the educational 
content offered by IBM Cognos located at 

http://www-304.ibm.com/jct03001c/services/learning/ites.wss/zz/en? 
pageType=page&c=R985771 H68561 El 6. 

Applicability 

The product behaviours described in this document were validated using: 



• IBM Cognos Business Intelligence 10.1.1 



IBM Cognos Active Report Overview 

IBM Cognos Active Report is a report output type that was introduced in IBM 
Cognos Business Intelligence 10.1 that allows professional report authors to create 
interactive reporting applications. The following sections will highlight the features, 
use cases and deployment options for IBM Cognos Active Report. 

Key Features 

There are many features that are unique to IBM Cognos Active Report that allow the 
solution to deliver new value to IBM customers. Some of the solution's key features 
include: 

Disconnected 

An IBM Cognos Active Report is a stand-alone, self-contained file. This allows users 
to fully interact with all of the content in their reporting application without being 
dependent on connectivity to their IBM Cognos Bl server. Disconnected reporting 
simplifies report distribution and consumption within an organization and makes Bl 
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content readily available to external partners and customers. 

Highly Interactive 

IBM Cognos Active Report controls enable a new level of interactive behaviour. 
When combined with the solution's speed of thought performance, business users 
are provided with an engaging end user experience. The flexibility provided by the 
report controls allows a single reporting application to meet the needs of many 
users, eliminating the need to customize reports to suit personal viewing 
preferences. 

Portable 

Business users need access to their Bl information regardless of their location, 
connectivity or consumption device. The same IBM Cognos Active Report can be 
consumed in standard web browsers and on the Apple iPad while connected or 
disconnected from the network. This ensures that business users always have their 
IBM Cognos Bl content available at their fingertips. When consuming an IBM 
Cognos Active Report in the IBM Cognos Mobile native iPad application, standard 
report controls are automatically given the native iOS look and feel and interactive 
gestures such as swiping are enabled. This ensures that users are provided with the 
native iPad experience that they demand without creating the need for the 
professional report author to create device specific reports. Additionally, IBM Cognos 
Active Report content can be consumed in IBM Cognos Business Insight where it 
can be viewed side by side with your organization's broad analytic content. 

Access to Details on Demand 

By leveraging drill-through functionality while connected to the IBM Cognos Bl 
server, a business user can drive a deeper analysis without losing context. This 
allows a user to leverage the performance and interactivity of an IBM Cognos Active 
Report without sacrificing easy access to additional IBM Cognos content. 

Broad Distribution 

IBM Cognos Active Report outputs are intuitive to navigate and can be consumed in 
standard web browsers. This allows a broad base of users to immediately benefit 
from the full power of a contained IBM Cognos Bl solution. In addition, the IBM 
Cognos Active Report output can be distributed using the existing scheduling and 
bursting functionality already available within IBM Cognos. 

IBM Cognos Platform Security 

IBM Cognos Active Report content respects all existing IBM Cognos platform 
security features. When a user in IBM Cognos Connection runs a reporting 
application or an administrator schedules and bursts reporting applications to a 
group of users, all role based security policies will be honoured. Each user will 
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consume a reporting application that contains only the data that they are authorized 
to view. 

Single Authoring Environment 

IBM Cognos Report Studio is used to create standard report output types and IBM 
Cognos Active Report content. As a result, existing reports can be converted into 
interactive reporting applications with a single click. This allows existing queries and 
chart objects to be reused and reduces the amount of time required to build 
interactive reporting applications. 

Common Use Scenarios 

The features of IBM Cognos Active Report make it a flexible and portable solution 
whose benefits can be leveraged across an entire organization and beyond. In order 
to ensure a successful deployment, it is important to apply the technology to the 
proper use cases. Some of the ideal use cases for IBM Cognos Active Report 
include: 

Enabling the Mobile Workforce 

Mobility is on the rise and is becoming a way of life. Business users expect to be 
able to consume their business information at anytime regardless of their location or 
what device they are using. IBM Cognos Active Report enables the mobile workforce 
by allowing the exact same reporting application to be consumed on the Apple iPad 
and in standard web browsers. When combined with the disconnected nature of the 
solution, IBM Cognos Active Report ensures users have the right information to 
make business decisions while on the go. 

Managed Dashboards 

Business users expect visually appealing, high performance and interactive 
dashboards that are able to communicate key business information. IBM Cognos 
Active Report allows the professional report author to create managed dashboards 
that can be distributed to a broad audience. The wide array of IBM Cognos Active 
Report controls ensures that the desired functionality can be achieved and an 
engaging end user experience can be delivered to business users. The reporting 
applications are high performance stand-alone files and by leveraging drill through 
technology, business users can seamlessly connect to more detailed data without 
losing context. IBM Cognos Active Report allows business users' most common data 
to be presented in an interactive manner but also provides a simple path for driving a 
deeper analysis. 

Extending Bl to External Customers or Partners 

Businesses can improve their relationships with customers and increase synergies 
with partners by improving the flow of information to external users. IBM Cognos 
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Active Report technology allows interactive reports to be distributed outside the 
organization without having to worry about granting those users access to the IBM 
Cognos server. The solution provides a scalable and secure way of sharing 
information outside the organization without creating an increased support burden. 

Deployment Strategies 

The portability of IBM Cognos Active Report creates many possible deployment 
options. IBM Cognos administrators should consider the intended audience and use 
case when choosing which method is most suitable. Some of the most common 
scenarios include: 

Email Distribution 

IBM Cognos Active Report content can be distributed through secure corporate 
email, which will then allow the recipients to fully interact with all of the data 
regardless of their connectivity to the IBM Cognos Bl server. Scheduling and 
bursting can be used to ensure that this operation occurs at a non-peak server time 
to reduce system loads. Additionally, leveraging scheduling and bursting ensures 
that IBM Cognos role based security restrictions will be honoured. This is a suitable 
deployment option for distributing IBM Cognos Active Report content to a controlled 
audience, which could be both internal and external. 

Mobile Distribution 

The IBM Cognos Mobile native iPad application has the ability to pull IBM Cognos 
Active Report content to the device in several ways. Scheduling and bursting can be 
used to send content directly to an end user's iPad. After the report is run on the IBM 
Cognos Bl server, the IBM Cognos Mobile Service transfers the report output to the 
iPad as soon as the user logs in from their device. Once the content is transferred, it 
becomes available for offline consumption. Alternatively, the IBM Cognos 
Connection folder structure can be browsed from the native iPad application and the 
user can choose to run any IBM Cognos Active Report that they are authorized to 
access. After running the report, it will be stored locally on the iPad and available for 
disconnected consumption. Under both of these deployment scenarios the reporting 
content is protected by an initial IBM Cognos Bl server authentication and role based 
security restrictions. The iPad application also supports email distribution. When a 
user is sent a reporting application as an attachment to an email, the file will be 
associated with the IBM Cognos Mobile iPad application and can be directly 
launched into this environment. The output will then be saved within the application 
for offline consumption. Scheduling and bursting is the recommended deployment 
scenario for the mobile workforce as this ensures that the users' IBM Cognos Bl 
content is downloaded and made available for offline consumption whether or not 
they chose to run that specific report before becoming disconnected. 
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Network Accessible Location 

IBM Cognos Active Report output is a self-contained output. As a result, the 
single-file output can be placed in a shared location and made accessible to anyone 
who has access to this network location. Security can be provided via password or 
login credentials for the remote location to ensure that only people who are 
authorized to view the content have access to the report. This deployment scenario 
eliminates the need to email a copy of the file to every recipient, which can reduce 
network loads. Since a single version of the output is shared, each user consumes 
the same reporting application and role based security is not honoured. 

IBM Cognos Connection 

As is the case with standard IBM Cognos reports, IBM Cognos Active Report 
content resides in IBM Cognos Connection. Assuming the user has the proper folder 
permissions and privileges, users can easily navigate to the location of the report 
and gain access to the reporting application. The user can choose to view an 
existing saved output or re-run the report to get the freshest data possible. By 
leaving the reports in IBM Cognos Connection, every user must authenticate with 
the IBM Cognos Bl server before gaining access. Additionally, all IBM Cognos role 
based security will remain intact when a user chooses to run the report. If the end 
user has not manually downloaded the report from IBM Cognos Connection to their 
local machine, the content will be inaccessible while disconnected from the server. 

Restricting Consumption 

Not all IBM Cognos users are authorized to consume IBM Cognos Active Report 
content. Users must be a named user of Active Report Recipient or at least 
Enhanced Consumer in order to consume IBM Cognos Active Report content. 
Alternatively, a PVU based Active Report Recipient license can be purchased so 
that the reporting applications can be distributed across the entire organization and 
shared externally. 

To ensure license compliance, several techniques can be used. An access code can 
be placed on the IBM Cognos Active Report output. The author of the report controls 
this and the access code is the same for all users. Additionally, IBM Cognos Active 
Report content can be contained in folders with permissions so that unauthorized 
users are unable to get access to the reports. Finally, deployment scenarios that 
distribute the content to a controlled group, such as email or mobile distribution, can 
be used to ensure that only the intended audience receives the reporting output. 
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The IBM Cognos Active Report Toolbox Items 

The following section provides an overview of each of the IBM Cognos Report 
Studio toolbox items that can be used to create an IBM Cognos Active Report 
application. This section will also provide a step-by-step example on how to use 
some of these items. 

Variable Text Item 

The Variable Text Item is used to display the value of an IBM Cognos Active Report 
variable. This toolbox item is equivalent to the IBM Cognos Report Studio Report 
Expression, ParamDisplayValue. 

Variable Text Item Step by Step 

The following example will step a user through creating a variable, assigning a value 
to the variable and displaying it on an IBM Cognos Active Report using the Variable 
Text Item. 



1 . Within IBM Cognos Report Studio, create a new Blank Active Report. 

2. Click on the Active Report Variables tab and click the Create a new 
variable link. 

The following screen capture displays IBM Cognos Report Studio with the 
Active Report Variable tab selected. It also displays the Active Report 
Variable dialog box that is presented to the user after clicking the Create 
a new variable link. The Active Report Variable dialog box consists of a 
Name field, a Data Type selection drop-down and a Set Default Value(s) 
link which can be used to specify default variable values. 

Figure 1 IBM Cognos Report Studio displaying the Active Report 
Variable dialog box 
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3. Within the name field of the Active Report Variable dialog box, add the 
name varMyActiveReportVariable. 

4. Click the Set Default Value(s) link to display the Default Variable Values 
dialog box. 

5. Within the Default Variable Values dialog box, click the New icon at the 
bottom left of the dialog box. 

6. Enter a default value of MyVariableValue and click the OK button. 

7. Click the OK button to close the Active Report Variable dialog box. 

8. From the available Toolbox items, locate the Variable Text item and drag 
it into the report. Since there is only one IBM Cognos Active Report 
variable defined, the Variable Text Item is automatically associated to this 
variable. If multiple variables have defined, the report author will be 
prompted to pick a variable. 

If the IBM Cognos Active Report is executed it will display the text 
MyVariableValue for the varMyActiveReportVariable Variable Text Item. 



Row Number 

The Row Number is used to ensure that the row number in a list is properly 
displayed as it is dynamically filtered by controls. By including the Row Number 
object in a list column, the rows will always be numbered sequentially beginning at 
one as the list is manipulated. 



Deck 

A Deck provides the report author the ability to manually create the desired number 
of cards. Decks are useful when the content displayed on the cards differ from card 
to card. 

Deck Item Step by Step 

The following example provides the step by step instructions on how to use a Deck 
item that is controlled by a Radio Button Group to display the same data in a 
crosstab and a chart. 



1 . Within IBM Cognos Report Studio, create a new Blank Active Report. 
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2. From the available Toolbox items, drag the Radio Button Group object 
onto the report canvas. 

3. Click on the Radio Buttons Definition icon located to the right of the Radio 
Button Group object. 

4. Within the Radio Buttons Definition dialog box, delete Button Label 3 by 
clicking the X that appears when you hover to the left of the entry. 

5. Rename Button Label 1 to Crosstab and Button Label 2 to Line Chart. 

6. Click the OK button to return to the report page. 

7. Click on the Radio Button Group and within the bottom left hand 
Properties pane change the Name property within the Miscellaneous 
section to Crosstab/Chart Radio Control. 

8. From the available toolbox items, locate the Deck item and drag it 
underneath the Radio Button Group control. 

9. Click on the Edit Deck Cards Definition icon located to the right of the 
Deck item. 

10. Within the Deck Cards Definition dialog box, delete Card 3 by clicking the 

X. 

1 1 . Rename Card 1 to Crosstab and Card 2 to Line Chart. 

1 2. Click the OK button to return to the report page. 

1 3. Click on the Deck and within the bottom left hand Properties pane change 
the Name property within the Miscellaneous section to Crosstab/Chart 
Deck. 

1 4. From the available Toolbox items, drag the Crosstab object onto the 
Crosstab card. 

1 5. Using the available Source items, populate the Crosstab object with the 
GO Sales(query)\Sales(query)\Products\Product line on the rows, the GO 
Sales(query)\Sales(query)\Time\Year as the columns and GO 
Sales(query)\Sales(query)\Sales\Revenue as the measure. Once 
completed, the report page should now consist of two radio buttons at the 
top of the screen that are labelled Crosstab and Line Chart. Within the 
Deck, one of the cards is labelled Crosstab. The Crosstab card contains a 
Crosstab object that has been populated with Product line on the rows, 
Year on the columns and Revenue as the measure. This is also depicted 
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by the image below. 

Figure 2 IBM Cognos Report Studio displaying a Deck with the 
Crosstab card populated 
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1 6. Select the Line Chart card from the Deck drop down. 



1 7. From the available Toolbox items, drag the Chart object onto the Line 
Chart card. 



1 8. Within the Insert Chart dialog box, select line chart and press the OK 
button. 



1 9. Using the available source items, populate the Line Chart object with the 
GO Sales(query)\Sales(query)\Products\Product line on the Series, the 
GO Sales(query)\Sales(query)\Time\Year as the Categories and GO 
Sales(query)\Sales(query)\Sa!es\Revenue as the measure. 

20. Click the Create a New Connection icon to the right of the Radio Button 
Group control. 



21 . Within the Create a New Connection dialog box ensure the Source is the 
Crosstab/Chart Radio Control and the Target Control is the 
Crosstab/Chart Deck. The Active Report Variable should be the Label 
with a Default Value of the Line Chart. 
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Figure 3 IBM Cognos Active Report Connection dialog displaying 
the connection between the Radio Button Group and the Deck 
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22. Click the Connect button to make the connection and return to the report 
page. 

If the IBM Cognos Active Report is executed, it will display two radio 
buttons. One named Crosstab and the other named Line Chart. By default 
the user is presented with the Line Chart. The user then has the ability to 
switch the view to a crosstab by selecting the Crosstab radio button. 



Data Deck 

The Data Deck object is used to automatically create a card for each data item value 
used to drive the Data Deck. Data Decks are useful if the number of cards is 
unknown due to changing data. Data Decks are generally used to display the same 
report data container for different contexts. 

Data Deck Item Step by Step 

The following example provides the step by step instructions on how to use a Data 
Deck item that is controlled by a Button Bar to display a list for each product line. 



1 . Within IBM Cognos Report Studio, create a new Blank Active Report. 

2. From the available Toolbox items, drag the Data Button Bar object onto 
the report canvas. 
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3. 


Click on the Data Button Bar and within the bottom left hand Properties 
pane change the Name property within the Miscellaneous section to 
Product line Data Button Bar. 


4. 


Within the Query Explorer tab, click on Queryl . Within the bottom left 
hand Properties pane, locate the Miscellaneous section and change the 
name of the query from Queryl to Data Button Bar/Deck Query. 


5. 


Using the Page Explorer tab, return to the report view by clicking on 
Pagel . 


6. 


From the available Source items, locate the GO 
Sales(query)\Sales(query)\Products\Product line and drag it into Labels 
section of the Data Button bar. 


7. 


From the available Toolbox items, hold the right mouse button and drag 
the Data Deck object onto the report canvas. 


8. 


After releasing the right mouse button, a menu appears. Select the option 
Insert using existing query. 


9. 


When prompted for a query, select Data Button Bar/Deck Query and 
press the OK button. 


10. 


Click on the Data Deck and within the bottom left hand Properties pane 
change the Name property within the Miscellaneous section to Product 
Line Data Deck. 


11. 


From the available Toolbox items, locate the List query object and drag it 
into the Data Deck. 


12. 


Within the Query Explorer tab, click on Queryl . Within the bottom left 
hand Properties pane, locate the Miscellaneous section and change the 
name of the query from Queryl to List Query. 


13. 


Using the Page Explorer tab, return to the report view by clicking on 
Pagel . 

After completing this step, the IBM Cognos Active Report should consist 
of a Data Button Bar at the top of the screen with the Product line query 
item inserted into the Labels drop area. Underneath the Data Button Bar, 
a Data Deck was inserted within which an empty List object was inserted. 
This is also illustrated by the following screen capture. 
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Figure 4 The IBM Cognos Active Report with a Data Button Bar and 
Data Deck containing a List object 
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1 4. From the available Source items, locate the GO 
Sales(query)\Sales(query)\Products\Product line and drag it into the List 
object. 

15. Within the Data Item tab, select the Product line data item and drag it into 
the Values drop zone of the Data Deck. After completing this step, the 
IBM Cognos Active Report should consist of a Data Button Bar at the top 
of the screen with the Product line query item inserted into the Labels 
drop area. Underneath the Data Button Bar, a Data Deck now contains a 
List object populated with the Product line query item. The Product line 
query item was also used to populate the Values drop zone of the Data 
Deck. The current report layout is illustrated by the following screen 
capture. 

Figure 5 The IBM Cognos Active Report with a Data Button Bar and 
Data Deck containing a List object populated with the Product line 
query item 
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1 6. Select the List object and within the left hand Properties pane under the 
Data section, select the Master Detail Relationships property by clicking 
the ellipsis. 

17. Within the Master Detail Relationships dialog box, define a relationship 
between the Data Button Bar/Deck Query and the List Query by clicking 
the New Link. 

1 8. Click the OK button to commit the relationship and return back to the 
report page. 

1 9. Select the Data Button Bar object and right click to display the available 
menu. 

20. From the available menu select Create a New Connection. 

21 . Within the Create a New Connection dialog box, ensure that the Source 
Control is the Product Line Data Button Bar, the Target Control is the 
Product Line Data Deck and the Active Report Variable section has a 
variable defined with the name varProductLine, a data type of String and 
a default value of Camping Equipment. The completed dialog box is also 
illustrated by the following screen capture. 

Figure 6 Create a New Connection dialog box linking the Data Button 
Bar to the Data Deck 
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22. Click the Connect button to create the connection. 

If the IBM Cognos Active Report is executed, it will display a button for 
each of the product lines at the top of the report. Each button will display 
a List that has been filtered to the appropriate product line when pressed. 
This is also illustrated by the following image. 

Figure 7 IBM Cognos Active Report output showing a single record 
list with the same data as the pressed button 
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Tab Control 

A Tab Control provides the report author the ability to manually create the desired 
number of Tabs. 

Tab Control Item Step by Step 

The following example provides the step by step instructions on how to use a Tab 
Control to display either a crosstab or chart view of the same data. 



1 . Within IBM Cognos Report Studio, create a new Blank Active Report. 

2. From the available Toolbox items, drag the Tab Control object onto the 
report canvas. 

3. Click on the Tab Control and within the bottom left hand Properties pane 
change the Name property within the Miscellaneous section to 
Crosstab/Chart Tab Control. 

4. Click on the Tab Definition Icon located to the right of the physical tabs. 

5. Delete Tab label 3 by hovering the mouse over it and clicking the X. 

6. Rename Tab label 1 to Crosstab and Tab label 2 to Line Chart. 

7. Press the OK button to return to the report page. When completed the 
report page should now display two tabs at the top of the screen. The first 
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tab should be labelled Crosstab and the second Line Chart. This is also 
illustrated by the following screen capture. 

Figure 8 IBM Cognos Report Studio displaying the IBM Cognos 
Active Report Tab Control 




8. From the available Toolbox items, drag the Crosstab object onto the 
Crosstab tab. 

9. Using the available source items, populate the Crosstab object with the 
GO Sales(query)\Sales(query)\Products\Product line on the rows, the GO 
Sales(query)\Sales(query)\Time\Year as the columns and GO 
Sales(query)\Sales(query)\Sales\Revenue as the measure. 

10. Click on the Line Chart tab. 

1 1 . From the available Toolbox items, drag the Chart object on the Line Chart 
tab. 

1 2. Within the Insert Chart dialog box, select Line chart and press the OK 
button. 

1 3. Using the available source items, populate the Line Chart object with the 
GO Sales(query)\Sales(query)\Products\Product line on the Series, the 
GO Sales(query)\Sales(query)\Time\Year as the Categories and GO 
Sales(query)\Sales(query)\Sales\Revenue as the measure. 

If the IBM Cognos Active Report is executed, it will display two tabs. One 
named Crosstab and the other named Line Chart. By default the user is 
presented with the Line Chart. The user then has the ability to switch the 
view to a crosstab by clicking on the Crosstab tab. 

Data Tab Control 

A Data Tab Control provides the report author the ability to create Tabs based on 
the number of records returned by a data item. A Data Tab Control can be effective 
when the number of tabs required needs to change when the record set of a data 
item changes. 
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Button Bar 

A Button Bar provides the report author the ability to manually create the desired 
number of buttons. 

Data Button Bar 

A Data Button Bar provides the report author the ability to create buttons based on 
the number of records returned by a data item. A Data Button Bar can be effective 
when the number of buttons required needs to change when the record set of a data 
item changes. 

Toggle Button Bar 

A Toggle Button Bar provides the report author the ability to display manually 
created selectable buttons. These buttons can be used to dynamically filter a data 
container. 

Data Toggle Button Bar 

A Data Toggle Button Bar provides the report author the ability to display multiple 
selectable buttons based on the number of records returned by a data item. 

Data Toggle Button Bar Step by Step 

The following example provides the step by step instructions on how to use a Data 
Toggle Button Bar to dynamically filter a list object based on the selected buttons of 
the Data Toggle Button Bar. 



1 . Within IBM Cognos Report Studio, create a new Blank Active Report. 

2. From the available Toolbox items, drag the Data Toggle Button Bar object 
onto the report canvas. 

3. Click on the Data Toggle Button Bar and within the bottom left hand 
Properties pane change the Name property within the Miscellaneous 
section to ProductLine List ToggleButtonBar. 

4. Within the Query Explorer tab, click on Queryl . Within the bottom left 
hand Properties pane, locate the Miscellaneous section and change the 
name of the query from Queryl to Data Button Bar/List Query. 

5. Using the Page Explorer tab, return to the report view by clicking on 
Pagel . 
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6. From the available Toolbox items, right click and drag the List object onto 
the report canvas below the Data Toggle Button Bar. 

7. After releasing the right mouse button, a menu appears. Select the option 
Insert using existing query. 

8. When prompted for a query, select Data Button Bar/List Query and press 
the OK button. 

9. Using the available source items, populate the List object with GO 
Sales(query)\Sales(query)\Products\Product line and GO 
Sales(query)\Sales(query)\Sales\Revenue. 

10. From the available Data Items drag Product line into the Labels drop zone 
of the Data Toggle Button Bar. When completed, the IBM Cognos Active 
Report should have a Data Toggle Button Bar populated with Product 
line. Underneath the Data Toggle Button Bar a List has been populated 
with Product line and Revenue. This is also illustrated by the following 
screen capture. 



Figure 9 IBM Cognos Report Studio displaying the Data Toggle 
Button Bar and List data object 
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1 1 . Click the Create a New Connection icon to the right of the Toggle Button 
Bar control. 

12. Within the Create a New Connection dialog box ensure the Source is the 
ProductLine List ToggleButtonBar and the Target Control is Listl . The 
Behavior drop down list was changed from Select to Filter and an IBM 
Cognos Active Report variable name varProductLine was created. The 
varProductLine also has the default value of ‘Camping Equipment’, ‘Golf 
Equipment’ and ‘Mountaineering Equipment’ set. This is illustrated by the 
following screen capture. 
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Figure 10 IBM Cognos Active Report Create a New Connection 
dialog box creating the connection between the control and the list 
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1 3. Click the Connect button to create the connection. 

If the IBM Cognos Active Report is executed, it will display a button for 
each of the product lines at the top of the report. As each button is 
clicked, the List object refreshes including only the product lines whose 
buttons have been selected. In the following example, the user has 
selected the Camping Equipment and Golf Equipment buttons. The list 
therefore only displays those two product lines and their associated 
revenue. 

Figure 11 IBM Cognos Viewer output displaying the Toggle Button 
Bar with two values selected 

Cyiprg Ecuo^itnt Gof Ec.c^'t ! Eo-©<t*c: Outdoor P’otfctc^ Prrc^*' Acc*«on«* 

tVoO.d l r • Gr 

St S£s. 2 M U* 03 
C^tQ.C'Tl ST»t1tX7r> 



Radio Button Group 

A Radio Button Group provides the report author the ability to manually supply the 
available selections displayed as a radio button choice. These values can be used to 
filter or select the data of a data container one radio button value at a time. 
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Data Radio Button Group 

A Data Radio Button Group provides the report author the ability to supply the 
available selections as a radio button choice based on the record set returned by a 
specified data item. These values can be used to filter or select the data of a data 
container one radio button value at a time. 

Check Box Group 

A Check Box Group provides the report author the ability to manually supply the 
available selections displayed as check boxes. The items selected in check boxes 
can be used to filter the data of a data container. 

Data Check Box Group 

A Data Check Box Group provides the report author the ability to display multiple 
selectable check boxes based on the number of records returned by a data item. 
These check boxes can be selected in multiples and used to dynamically filter a data 
container. 

Data Check Box Group Step by Step 

The following example provides the step by step instructions on how to use the 
Convert Control menu option to convert the previous Data Toggle Button Bar 
example into a Data Check Box Group which then dynamically filters a list object 
based on which check boxes are selected. 



1 . Within IBM Cognos Report Studio, create a new Blank Active Report. 

2. From the available Toolbox items, drag the Data Toggle Button Bar object 
onto the report canvas. 

3. Click on the Data Toggle Button Bar and within the bottom left hand 
Properties pane change the Name property within the Miscellaneous 
section to ProductLine List ToggleButtonBar. 

4. Within the Query Explorer tab, click on Queryl . Within the bottom left 
hand Properties pane, locate the Miscellaneous section and change the 
name of the query from Queryl to Data ToggleButtonBar/List Query. 

5. From the available Toolbox items, hold the right mouse button and drag 
the List object onto the report canvas. 

6. After releasing the right mouse button, a menu appears. Select the option 
Insert using existing query. 
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7. When prompted for a query, select ProductLine List ToggleButtonBar 
Query and press the OK button. 

8. Using the available source items, populate the List object with the GO 
Sales(query)\Sales(query)\Products\Product line and GO 
Sales(query)\Sales(query)\Sa!es\Revenue. 



9. From the available Data Items drag Product line into the Labels drop zone 
of the Data Toggle Button Bar. When completed, the IBM Cognos Active 
Report should have a Data Toggle Button Bar populated with Product 
line. Underneath the Data Toggle Button Bar a List has been populated 
with Product line and Revenue. This is also illustrated by the following 
screen capture. 



Figure 12 IBM Cognos Report Studio displaying the Data Toggle 
Button Bar and List data object 
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1 0. Click the Create a New Connection icon to the right of the Toggle Button 
Bar control. 



1 1 . Within the Create a New Connection dialog box ensure the Source is the 
ProductLine List ToggleButtonBar and the Target Control is Listl . The 
Behavior drop down list was changed from Select to Filter and an IBM 
Cognos Active Report variable name varProductLine was created. The 
varProductLine also has the default value of ‘Camping Equipment’, ‘Golf 
Equipment’ and ‘Mountaineering Equipment’ set. This is illustrated by the 
following screen capture. 
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Figure 13 IBM Cognos Active Report Create a New Connection 
dialog box creating the connection between the control and the list 
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1 2. Click the Connect button to create the connection. 



1 3. Select the Data Toggle Button Bar control and right click. From the 
available menu items select Convert Control. 



14. From the available list, select Data Check Box Group. 



1 5. Select the Data Check Box Group and within the bottom left hand side 
Properties pane under the Miscellaneous section, change the Name 
property from ProductLine List ToggleButtonBar to ProductLine List 
DataCheckBoxGroup. 

If the IBM Cognos Active Report is executed, it will display a check box 
for each of the product lines at the top of the report. As each check box is 
selected, the List object refreshes to include only the product lines whose 
check boxes have been selected. In the following example, the user has 
selected the Camping Equipment and Golf Equipment check boxes. The 
list therefore only displays those two product lines and their associated 
revenue. 
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Figure 14 IBM Cognos Viewer output displaying the Check Box 
Group with two values selected 
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Drop-Down List 

A Drop-Down List provides the report author the ability to manually supply the 
available selections displayed in a drop down list. The items selected in the 
Drop-Down List can be used to dynamically filter or select a data container. 

Data Drop-Down List 

A Data Drop-Down List provides the report author the ability to supply the available 
selections in a drop down list based on the record set returned by a specified data 
item. The items selected in the Data Drop-Down List can be used to dynamically 
filter or select a data container. 

List Box 

A List Box provides the report author the ability to manually supply the available 
selections displayed in a List Box. The items selected in the List Box can be used to 
dynamically filter or select a data container one value at a time. Multi-select can also 
be enabled by setting the Multi-Select property to Yes. 

Data List Box 

A Data List Box provides the report author the ability to supply the available 
selections in a drop down list based on the record set returned by a specified data 
item. The items selected in the Data List Box can be used to dynamically filter or 
select a data container one value at a time. Multi-select can also be enabled by 
setting the Multi-Select property to Yes. 

Iterator 

A static Iterator is a control that allows users to navigate through values by using 
buttons such as first, last, previous and next. The control provides the report author 
the ability to manually supply the available selections. When connected to a variable 
it will allow the iterator control to filter or select values from a data container. 
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Data Iterator 

A Data Iterator is a control that allows users to navigate through values by using 
buttons such as first, last, previous and next. The control provides the report author 
the ability to supply the available values based on the record set returned by a 
specified data item. When connected to a variable it will allow the iterator control to 
filter or select values from a data container. 

Data Iterator Step by Step 

The following example provides the step by step instructions on how to use a Data 
Iterator to dynamically select values from a deck. 



1 . Within IBM Cognos Report Studio, create a new Blank Active Report. 

2. From the available Toolbox items, drag the Table object onto the report 
canvas. 

3. On the Insert Table dialog box set the Number of columns to 3 and 
Number of rows to 1 and then click the OK button. 

4. From the available Toolbox items, drag the Data Iterator object onto the 
report canvas and place it in the first cell of the table. 

5. Click on the Data Iterator and within the bottom left hand Properties pane 
change the Name property within the Miscellaneous section to 
ProductLine_Data_lterator. 

6. Within the Query Explorer tab, click on Queryl . Within the bottom left 
hand Properties pane, locate the Miscellaneous section and change the 
name of the query from Queryl to lterator_Deck_Query. 

7. Using the Page Explorer tab, return to the report view by clicking on 
Pagel . 

8. From the available Toolbox items, hold the right mouse button and drag 
the Data Deck object onto the report canvas and place the Data Deck in 
the middle cell of the table. 

9. After releasing the right mouse button, a menu appears. Select the option 
Insert using existing query. 

1 0. When prompted for a query, select lterator_Deck_Query and press the 
OK button. 

1 1 . Click on the Data Deck and within the bottom left hand Properties pane 
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change the Name property within the Miscellaneous section to 
ProductLine_Deck. 

12. Using the available Source items, populate the ProductLine_Data_lterator 
Label drop zone with the GO Sales(query)\Sales(query)\Products\Product 
line. 

13. From the available Data Items drag Product line from the 
lterator_Deck_Query into the Values drop zone of the Data deck named 
ProductLine_Deck. 

1 4. From the available Toolbox items, locate the List object and drag it into 
the Data Deck named ProductLine_Deck. 

1 5. From the available Source items, locate the GO 
Sales(query)\Sales(query)\Products\Product line, GO 
Sales(query)\Sales(query)\Products\Product type and GO 
Sales(query)\Sales(query)\Sales\Revenue and drag them into the List 
object. 

1 6. Within the Query Explorer tab, click on Queryl . Within the bottom left 
hand Properties pane, locate the Miscellaneous section and change the 
name of the query from Queryl to ProductList_Query. 

1 7. Using the Page Explorer tab, return to the report view by clicking on 
Pagel. 

1 8. Select the List object and within the left hand Properties pane, select the 
Master Detail Relationships property from the Data Section by clicking the 
ellipsis. 

19. Within the Master Detail Relationships dialog box, define a relationship 
between the lterator_Deck_Query and the ProductList_Query by clicking 
the New Link. The lterator_Deck_Query \ Product line data item should be 
linked to ProductList_Query \ Product line data item. 

20. Click the OK button to commit the relationship and return back to the 
report page. 

21 . Click the Create a New Connection icon to the right of the Data Iterator 
named ProductLine_Data_lterator. 

22. Within the Create a New Connection dialog box ensure the Source is the 
ProductLine_Data_lterator and the Target Control is ProductLine_Deck. 
The Behavior drop down list is set to the default of Select and the IBM 
Cognos Active Report variable name varProductLine was created. The 
varProductLine also has the default value of ‘Camping Equipment’ set. 
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This is illustrated by the following screen capture. 

Figure 15 IBM Cognos Report Studio displaying the Data Iterator and 
List data object 




23. Click the Connect button to create the connection. 

24. Select the ProductLine_Data_lterator in the left hand table cell, right click 
to display the context menu and choose Copy to place into the paste 
buffer. 

25. Select the far right cell of the table, right click to display the context menu 
and select Paste to add the Data Iterator to the cell. 

26. Select the newly copied Data Iterator named ProductLine_Data_lterator1 . 

27. Within the bottom left hand Properties pane, locate the General section 
and set: 



Iterator First to Hide 
Iterator Previous to Hide 
Iterator Label Area to Hide 
Iterator Next to Show 
Iterator Last to Hide 



28. Return to the left hand table cell and select the Data Iterator named 
ProductLine Data Iterator. 
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29. Within the bottom left hand Properties pane, locate the General section 
and set: 



Iterator First to Hide 
Iterator Previous to Show 
Iterator Label Area to Hide 
Iterator Next to Hide 
Iterator Last to Hide 



30. The completed layout is illustrated by the following screen capture. 

Figure 16 IBM Cognos Report Studio displaying the Data Iterators, 
List data object within a Data Deck 
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31 . The last few steps are layout clean up steps to make the Active Report 
more appealing and complete. Select a List column and within the bottom 
left hand Properties pane, click the triangular Ancestor button and select 
List Columns. 

32. Locate the Positioning section, select the Size and Overflow property and 
click the ellipsis on the right. 

33. In the Size & Overflow dialog box set the Width to 150 pixels. 

34. Click OK to save the settings. 

35. Click the triangular Ancestor button and select Table. 

36. Locate the Positioning section, select the Size and Overflow property and 
click the ellipsis on the right. 

37. In the Size & Overflow dialog box clear all values. 

38. Return to the canvas and control click and select all three table cells. 

39. Click the Left button on the Toolbar to align objects in the cell to the left. 

40. Click the Top button on the Toolbar to align objects in the cell to the top. 

41 . If the IBM Cognos Active Report is executed, it will display two iterators 
(one showing only Next and one showing only Previous) on either side of 
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the List report. As the Iterator buttons are clicked a different card is 
displayed. In the following example, the user has displayed the first card 
which has the value of Camping Equipment for the Product line column. 
Note that since this is the first value, the Prev button is disabled and the 
Next button is active. 



Figure 17 IBM Cognos Active Report output displaying the Data 
Iterator set to Camping Equipment 
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Discrete Values Slider 

A Discrete Values Slider provides the report author a slider which can be used to 
filter or select a data container based on values defined by the report author. The 
Discrete Values Slider is best suited for non numeric filtering or the selection of a 
data container. A Range can also be enabled so that multiple sequential items can 
be selected at the same time. 

Data Discrete Values Slider 

A Data Discrete Values Slider provides the report author a slider which can be used 
to filter or select a data container based on values obtained from a data item. The 
Data Discrete Values Slider is best suited for non numeric filtering or the selection of 
a data container. A Range can also be enabled so that multiple sequential items can 
be selected at the same time. 

Data Discrete Values Slider Step by Step 

The following example provides the step by step instructions on how to use a Data 
Discrete Values Slider to dynamically filter a list object based on its selected value. 



1 . Within IBM Cognos Report Studio, create a new Blank Active Report. 

2. From the available Toolbox items, drag the Data Discrete Values Slider 
object onto the report canvas. 

3. Click on the Data Discrete Values Slider and within the bottom left hand 
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Properties pane change the Name property within the Miscellaneous 
section to ProductLine List DiscreteValuesSlider. 

4. Within the Query Explorer tab, click on Queryl . Within the bottom left 
hand Properties pane, locate the Miscellaneous section and change the 
name of the query from Queryl to Data Slider/List Query. 

5. Using the Page Explorer tab, return to the report view by clicking Pagel . 

6. From the available Toolbox items, hold the right mouse button and drag 
the List object onto the report canvas. 

7. After releasing the right mouse button, a menu appears. Select the option 
Insert using existing query. 

8. When prompted for a query, select Data Slider/List Query and press the 
OK button. 

9. Using the available Source items, populate the List object with the GO 
Sales(query)\Sales(query)\Products\Product line and GO 
Sales(query)\Sales(query)\Sales\Revenue. 

10. From the available Data Items drag Product line into the Labels drop zone 
of the Data Discrete Values Slider. When completed, the IBM Cognos 
Active Report should have a Data Discrete Values Slider populated with 
Product line. Underneath the Data Discrete Values slider, a List has been 
populated with Product line and Revenue. This is also illustrated by the 
following screen capture. 



Figure 18 IBM Cognos Report Studio displaying the Data Discrete 
Values Slider and List data object 
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1 1 . Click the Create a New Connection icon to the right of the Data Discrete 
Value Slider. 

12. Within the Create a New Connection dialog box ensure the Source is the 
ProductLine List DiscreteValuesSlider and the Target Control is Listl . The 
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Behavior drop down list was changed from Select to Filter and an IBM 
Cognos Active Report variable name varProductLine was created. The 
varProductLine also has the default value of ‘Mountaineering Equipment’ 
set. This is illustrated by the following screen capture. 



Figure 19 IBM Cognos Active Report Create a New Connection 
dialog box creating the connection between the control and the list 
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1 3. Click the Connect button to create the connection. 



1 4. Select the Data Discrete Values Slider and within the bottom left 
Properties pane under the General section, change the Orientation 
property from Horizontal to Vertical. 

If the IBM Cognos Active Report is executed, it will display a slider with a 
value for each of the product lines at the top of the report. Currently, every 
time the slider is dragged and released the list will update to display the 
selected product line and its associated revenue. If the Update Variables 
Live property of the Data Discrete Values Slider is set to Yes, then as the 
slider is moved, the List object will update without the user having to 
release the slider. In the following example, the user has placed the slider 
on the Personal Accessories value. The list therefore only displays that 
product line and its associated revenue. 
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Figure 20 IBM Cognos Active Report output displaying the Data 
Discrete Values slider set to Personal Accessories 
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Continuous Values Slider 

A Continuous Values Slider provides the report author a slider which can be used to 
filter or select a data container based on manually entered numeric values. The 
Continuous Values Slider is best suited for numeric range filtering. The range 
settings can be controlled in the Properties panel when the Continuous Values Slider 
is selected. 

Button 

The Button Toolbox item can be used to add additional interactivity to an IBM Active 
Report. The IBM Cognos Active Report Button can be used to select or filter a 
container. It can also be used to enable a control or set a variable. 

Button Step by Step 

The following example provides the step by step instructions on how to use a Data 
Toggle Button Bar to dynamically filter a list object based on the selected buttons of 
the Data Toggle Button Bar. It also provides the steps on how to use a button to 
enable the Data Toggle Button Bar which has been disabled by default. 



1 . Within IBM Cognos Report studio, create a new Blank Active Report. 

2. From the available Toolbox items, drag the Data Toggle Button Bar object 
onto the report canvas. 
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3. Click on the Data Toggle Button Bar and within the bottom left hand 
Properties pane change the Name property within the Miscellaneous 
section to ProductLine List ToggleButtonBar. 

4. Within the Query Explorer tab, click on Queryl . Within the bottom left 
hand Properties pane, locate the Miscellaneous section and change the 
name of the query from Queryl to Data Button Bar\List Query. 

5. From the available Toolbox items, hold the right mouse button and drag 
the List object onto the report canvas. 

6. After releasing the right mouse button, a menu appears. Select the option 
Insert using existing query. 

7. When prompted for a query, select Data Button Bar\List Query. 

8. Query and press the OK button. 

9. Using the available Source items, populate the List object with the GO 
Sales(query)\Sales(query)\Products\Product line and GO 
Sales(query)\Sales(query)\Sales\Revenue. 

10. From the available Data Items drag Product line into the Labels drop zone 
of the Data Toggle Button Bar. When completed, the IBM Cognos Active 
Report should have a Data Toggle Button Bar populated with Product 
line. Underneath the Data Toggle Button Bar a List has been populated 
with Product line and Revenue. This is also illustrated by the following 
screen capture. 



Figure 21 IBM Cognos Report Studio displaying the Toggle Button 
Bar and List data object 
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1 1 . Click the Create a New Connection icon to the right of the Data Toggle 
Button Bar control. 
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12. Within the Create a New Connection dialog box ensure the Source is the 
ProductLine List ToggieButtonBar and the Target Control is Listl . The 
Behavior drop down list was changed from Select to Filter and an IBM 
Cognos Active Report variable name varProductLine was created. The 
varProductLine was given the default value of the set ‘Camping 
Equipment’, ‘Golf Equipment’ and ‘Mountaineering Equipment’. This is 
illustrated by the following screen capture. 



Figure 22 IBM Cognos Active Report Create a New Connection 
dialog box creating the connection between the control and the list 




1 3. Click the Connect button to create the connection. 

1 4. From the available Toolbox items, drag the Button object below the list 
object. 

1 5. Click on the Button to select it. Within the bottom left of Properties pane, 
under the General section, change the button Label to Enable IT!. 

1 6. Click on the Interactive Behavior icon to the right of the Button object. 

1 7. Within the Interactive Behavior dialog box, double click the Set Variable 
Values area. 

1 8. Within the Set Variable Values dialog box, click the Create a New 
Variable link. 
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1 9. Create a new variable named varEnableDisable with a default value of 
disable. 



20. Click OK to return back to the Set Variable Values dialog box. 

21 . Within the Set Variable values dialog box, leave the varProductLine value 
as “Do not set” but change the varEnableDisable value to “Enable” by 
selecting Type in a value. 

When completed, the Set Variable Values dialog box should display the 
varProductLine variable with a value of “Do not set” and the 
varEnableDisable variable set to the type in value of “Enable”. This is also 
illustrated by the following screen capture. 



Figure 23 IBM Active Report Set Variable Values dialog box with a 
value supplied to the varEnableDisable variable 
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22. Click the OK button to return to the Interactive Behavior dialog box. 

23. Click OK again to return to the report layout. 

24. Select the Interactive Behavior for the Data Toggle Button Bar. 

25. Within the Interactive Behavior dialog box, double click the Control Enable 
at the bottom right of the screen. 

26. In the Condition Enable dialog box, set the left Item to Value and type 
Enable in the corresponding text field. Set the right Item to Active Report 
Variable and ensure the variable varEnableDisable has been selected. 
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The operator drop down should be set to IN. This is also illustrated by the 
following screen capture. 

Figure 24 IBM Cognos Active Report Condition Configuration for 
enabling the Data Toggle Button Bar 




27. Click the OK button three times to return to the report layout. 

If the IBM Cognos Active Report is executed, it will display a button for 
each of the product lines at the top of the report with interactivity disabled. 
The button to enable the interactivity is displayed below the List object. 
Once this button is clicked the Data Toggle Button bar becomes active. 

As each button is clicked, the List object refreshes including only the 
product lines whose buttons have been selected. 



Guidelines to Building an IBM Cognos Active Report 

The following sections discuss recommended design practices and guidelines for 
some of the main areas of IBM Cognos Active Report content creation. Tips and 
techniques will also be presented in order to help authors implement better reporting 
applications. 

Microsoft Hypertext Archive (MHT) File Size 

Once loaded, an IBM Cognos Active Report output will respond instantly to user 
interactions. Depending on the amount of data packaged into the application and the 
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number of chart variations, the output file size will vary and the IBM Cognos Active 
Report load time will be impacted. 

IBM Cognos Active Report outputs are self contained so all of the data that is 
returned by the queries is included in the reports. As the amount of data increases, 
the MHT file size increases. To help limit the file size increase, there is a 
configurable property in the IBM Cognos Active Report Properties menu box that 
allows the author to set the maximum number of rows that a query can return. This 
property is set to a value of 5,000 by default. This value is by no means a hard limit 
as it is simply intended to make the IBM Cognos Report author aware when they are 
including large queries. 

When an IBM Cognos Active Report is created, a unique image of every chart 
variation is created. For example, let’s examine a report that contains a data deck 
driven by ‘Products’. The data card contains a line chart of revenue over the last five 
years and the Master Detail Relationship for the chart is configured to filter the chart 
based on ‘Products’. Therefore, a unique line chart exists for each member of 
‘Products’. Each of these unique charts is a generated image that is packaged into 
the MHT output file. As a result, if there are 25 members in ‘Products’ then there will 
be 25 images generated and packaged. If ‘Products’ and ‘Countries’ drive a deck 
then there is the number of members in ‘Products’ times the number of members in 
‘Countries’ unique combinations. An image will be generated for each one of these 
permutations. The larger the number of unique chart permutations that an author 
creates, the larger the size the MHT output file will be. 

Determining what an acceptable file size is for an IBM Cognos Active Report is a 
subjective exercise. In applications where users can tolerate a longer load time and 
the file is shared to all users as a saved output in IBM Cognos Connection or on a 
network drive then it is not unlikely that a file over 20MB would be acceptable. If 
users are looking for a high level dashboard for a quick overview of their business 
while on the go then smaller reports that load faster would be best. In order to build 
useful reports and ensure a successful deployment, the author must carefully 
examine the use case and determine the best course of action. 

To help keep file sizes to a minimum and thereby improve load time there are 
several techniques that an author can employ. The following tips and techniques can 
be applied in many situations. 

Query Filtering 

IBM Cognos Report authors should filter queries so that they include only the data 
that the end user is interested in. This is particularly important when a query is 
driving a data deck in order to avoid creating unnecessary images. Leveraging 
bursting technology to ensure that only data that is relevant to each user is included 
in their report is an effective way to manage file size without having to build multiple 
reports. 
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There is an advanced debug menu available when running an IBM Cognos Active 
Report application from IBM Cognos Report Studio. By pressing Control+Shift+D 
additional options in the right click menu will be enabled. The figure below illustrates 
the debug menu with the Show Variables, Reset Variables, Info, Print, Copy Tab 
Control Recordset and Show Tab Control Recordset as available menu options. The 
figure also illustrates the dialog that would appear by selecting the Info menu option 
or the Show Tab Control Recordset. The Info dialog box displays the number of 
records associated with each of the controls within the IBM Cognos Active Report 
application. The Show Tab Control Records set displays the actual records 
associated with the control. In this example there is a recordset for each of the 
regions so a sample record would consist of a field name of Region with a value of 
“Americas”. With this information the IBM Cognos Report author is able to determine 
how many charts have been created, how many controls are in the report and what 
records are included in the report. This is a valuable tool for ensuring the queries are 
filtered properly and no unnecessary data or images are included in the reporting 
application. 



Figure 25 The diagnostic information available from the right click menu 
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Keep Decks Simple 

Decks should only contain data that is unique to a card. Any common styling or 
static content should be placed outside of the deck in order to avoid it being 
unnecessarily duplicated. In the image below, the IBM Cognos Active Report 
application simply consists of a data button bar populated with the Product line query 
item. This data button bar is used to set a value for a variable which controls the left 
and right hand data decks, both of which are driven by Product line and contain the 
Product line query item. The data deck on the left has the formatting correctly 
applied to the block that contains the data deck. The data deck on the right has the 
formatting applied to the block that is inside the data deck and will be repeated for 
each card in the deck. The end result will appear the same to the end user but the 
output file size will be reduced if the styling is placed outside the deck because the 
styling is only included once in the output file. 



Figure 26 Styling on a deck versus styling on the deck’s container 




Classes and Layout Component Reference Objects 

Using classes is a way to ensure that styling elements are shared between objects. 
This helps to minimize the output file size. This is particularly true when styling 
objects in a deck because many copies of the same styling will otherwise be 
created. By using classes to style, significant improvements in file size have been 
observed. 

Leveraging layout component reference objects has a similar effect to using classes 
for styling. By using a layout component reference object, a single object is shared 
throughout the IBM Cognos Active Report application, which in turn, reduces the 
amount of duplication in the output file. Additionally, design changes can quickly be 
reflected across multiple objects or reports simply by changing the class or layout 
component reference object. 
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Simplifying the Authoring Experience 

As reports become more complex, it is important to maintain an understanding of the 
overall interaction model and the relationships that exist between the controls and 
the variables. An author will find the following tips useful as they begin to create 
advanced reporting applications. 



The Active Report Variables and Active Report Controls Tabs 

The image below illustrates the dialog boxes presented by selecting the tabs beside 
the toolbox icon in IBM Cognos Report Studio. The dialog box on the left hand side 
displays the Active Report Variables and the right hand side displays the Active 
Report Controls. The Active Report Variables tab shows the author all of the 
variables that have been created and allows the author to change the name of a 
variable, change default values and see what controls interact with each of the 
variables. The Active Report Controls tab complements the variable pane by 
showing which variables each control is set by and which variables each control 
sets. This information can also be accessed on a per control basis by hovering over 
a control’s interactive behaviour icon on the report canvas. This is very useful 
information for the author as they are trying to debug functionality or understand the 
interaction in a reporting application. 



Figure 27 The interactivity information that is shown in the Active Report 
Variables and the Active Report Controls tab 





Diligent Naming 

As more functionality gets added to an IBM Cognos Active Report application, 
default control, query and variable names become less meaningful. In order to 



IBM Cognos Active Report 10.1.1 Cookbook 
© Copyright IBM Corporation 201 1 



Trademarks 
Page 39 of 68 




developerWorks® 



ibm.com/developerWorks 



ensure that the proper controls are being connected with the correct variable when 
setting up interactive behaviour, everything should be given meaningful names. It is 
particularly useful to prefix all variable names with v or var so that they can easily be 
identified as variables. This practice will help ensure that the author can easily 
maintain and update the report moving forward. Giving meaningful names also 
makes it much easier to navigate helpful menus such as the IBM Cognos Active 
Report Variables panel and Query Explorer. The following image consists of three 
parts: the IBM Cognos Active Report Variable dialog box which displays a list of 
variable names that have been properly named with the var prefix, the Query 
Explorer dialog box, which displays a list of query objects appropriately named to 
allow for easy association to the report object that uses them and the IBM Cognos 
Report Studio properties pane. The IBM Cognos Report Studio properties pane 
illustrates that the Data Button Bar object has been appropriately named Product 
Line Button Bar under the Miscellaneous\Name property. 



Figure 28 Variables, queries and controls with meaningful names 
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Reusing Queries 

When authoring an IBM Cognos Active Report, a new query is created every time an 
object is dragged into the report. As a result, the number of queries in the report 
increases quickly and it becomes difficult to ensure that all queries are filtered and 
implemented properly. This situation can be simplified by reusing the same query for 
multiple controls that share the same information. A simple way to accomplish this is 
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to use a right-click and drag when adding a new control to the canvas. The author 
will then be prompted to associate this control with an existing query instead of 
having a new query created. 



Default Variables 

Where applicable, all variables should be assigned default values. This will ensure 
that when the reporting application is loaded the end user will be shown the proper 
data with the desired context. 



Nesting Data Containers 

To simplify the interactive behavior logic, an author should avoid nesting a data 
container inside another data container. Instead of creating a deck for ‘Products’ with 
a deck for ‘Years’ inside it, create a single deck for ‘Products’ and ‘Years’. A 
selection expression that is a combination of the variables containing the desired 
year and product can be used to choose the proper card. Alternatively, one of the 
variables can be used to filter the deck and the other variable can select which of the 
remaining cards to display. 



Testing and Debugging 

In addition to the report diagnostics that are discussed in section 4 . 1 .1 , there are 
several other strategies that can be used to help test and debug reporting 
applications. The following image illustrates the dialog box presented to the user 
after right clicking on a reporting application that has been run from IBM Cognos 
Report Studio. The debug dialog box consists of Show Variables, Reset Variable, 
Info, Print, Copy Tab Control Recordset and Show Tab Control Recordset. The 
bottom half of the image illustrates the dialog box presented to the user after 
selecting the Show Variables menu item. In this example the dialog box shows the 
report author that the vProductLine variable has a value of Golf Equipment along 
with several other variable name and value combinations. 

The Show Variables dialog box gives the author the current value of all variables 
and allows the author to understand how the variables are changing as a user 
interacts with the report. The Reset Variables option from the same right-click menu 
allows the report author to return the reporting application to its original state without 
having to exit the report. 
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Figure 29 Output of the View Variables debug menu 
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Appearance and Performance 

The timely interaction and visual appeal are two of the key features of an IBM 
Cognos Active Report that create a compelling end user experience. The following 
are some concepts to keep in mind when creating and styling a reporting application. 



Object Sizing 

Not all cards in a deck are necessarily the same size. When a different sized card is 
selected for viewing, other displayed objects may move to accommodate the new 
card. To the end user this appears as objects bouncing on the screen. This 
behaviour can be avoided by sizing objects. Fixed sizing can be applied to the 
objects on the card and to the deck to ensure they are all the same. Consistent 
object and deck sizing is also important when animation on the deck is enabled. If 
the size of a deck is not constrained and animation is enabled then the new card 
could potentially animate in from across the screen, which creates an undesirable 
experience for the end user. If the deck is set to the same size as the cards then the 
animation will be more natural because it will be constrained to only the area 
occupied by the objects in the card. The size of a control is configured by the Size & 
Overflow property in the Properties panel. Other properties such as horizontal and 
vertical padding can also be used to enforce spacing between various controls. 



In order to impose size constraints, the author can start at the bottom of the object 
hierarchy and then move upwards by using the Ancestor button that is shown within 
the following image. In this example, the object hierarchy is displayed as Card, 
Deck, Block, Tab Card, Tab Control, Page Body and Page. The lowest object in the 
hierarchy in this case would be the Card. By starting at the lowest level and moving 
up the hierarchy, the author can ensure that proper sizing propagates through the 
reporting application. 
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Figure 30 The Ancestor button allows the author to traverse the layout 
hierarchy 
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Bouncing can also appear on lists or crosstabs. As data is filtered, the width of the 
columns will automatically adjust to fit the data that is currently being shown. This 
behaviour can be avoided by assigning a fixed column width to every column of the 
list or crosstab. Additionally, it is important to keep in mind the amount of data that is 
contained in a list or crosstab when laying out a fixed size report. If the list changes 
to include more data then the height of the object will expand and push down the 
items below it. This will occur regardless of whether or not there is a size constraint 
on the height of the list and its container. To avoid this behaviour, the real estate 
allocated to the list should be set to the lists maximum size or it can be placed in a 
scrollable block. 
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Filtering versus Segmenting Data 

Performance gains can be realized by segmenting list or crosstab data onto multiple 
cards instead of using the filtering functionality in the interactive behaviour area. As 
more data is included in the list or crosstab the performance gains become more 
noticeable and the end user experience is improved. 

The following screen capture provides a visual representation of the differences 
between filtering and segmentation. The list report on the right hand side consists of 
Product line, Product type and Quantity. The Camping Equipment records are 
distributed throughout the list, interlaced with the other records in the list. This large 
list would need to be filtered to reveal only the Camping Equipment items. The left 
hand side shows multiple lists using the same data items that are included in the 
right hand list. Each list on the left includes only a single Product line. These 
individual lists can be constructed by including the larger list in a data deck that is 
driven by Product line with a Master Detail Relationship setup between the list and 
data deck. In this scenario, the author can then select which pre-filtered list should 
be presented to the end user. 



Figure 31 A list segmented into cards to provide filtering functionality with 
improved performance 
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Optimizing Data Deck Queries 

When working with dimensional data, if multiple dimensions drive a Data Deck and 
the fact table is large, it is possible to optimize the query and reduce the build time of 
the reporting application. Instead of dragging the dimensions into the Data Deck and 
having them put into the same query, a separate query should be built for each 
dimension and then a join operation with an expression of 1 = 1 should be used to 
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create a new query. The Set Cross Product Allowed property for the new query must 
be set to Allow. The dimensions can then be brought into the Data Deck from the 
new query. 

Aligning Data and Objects 

When laying out a reporting application, use the right, left, centre and top, middle, 
bottom alignment controls that are accessible through the IBM Cognos Report 
Studio toolbar to get the desired object orientation. The alignment should be done as 
close to the object as possible. For example, when trying to centre a chart, the 
alignment should be set on the block or table cell that contains the chart. As 
previously mentioned, using the Ancestor button is an effective way to select 
containers that are nearest to the object that needs to be aligned. 

Depending on the desired functionality an author needs to decide whether to use a 
block or a table as the object container. Tables are more flexible because rows or 
columns can be added to existing tables to quickly adjust a layout. They also support 
both horizontal and vertical alignment. Tables are unable to control the overflow of 
content so they get automatically increased in size if the contents are larger than the 
container. This behaviour can affect the layout of a fixed size dashboard. On the 
other hand, blocks do not support vertical alignment but they can control overflow by 
becoming a scrollable area or by clipping content. 

Background Effects & Images 

An author can use background effects or images to improve the visual appeal of 
reporting applications. It is important to note that for a background effect to appear, it 
needs to be applied to an area that is a fixed size. If relative sizing is used, the 
background effect for that area will not show up in the IBM Cognos Active Report. 

Scaling Chart Axes When Using a Data Deck 

When charts are used in a data deck and a Master Detail Relationship is set up, the 
maximum values of the data belonging to each chart can be significantly different. 
When this situation is encountered and the scale of the chart remains the same on 
each card, the resulting charts can end up being illegible. The same range for all 
instances of chart property can be used to address this issue. The property can be 
found in the Axis Range menu of the chart’s Primary Axis properties. When this 
setting is unchecked, the axes of each chart in the data deck will be scaled to the 
data contained in that specific chart. 

iPad Specific Guidance 

The same IBM Cognos Active Report can be consumed in standard web browsers 
and by the IBM Cognos Mobile native iPad application. If the use case for a specific 
reporting application is mobile centric and it will frequently be consumed on the iPad 
then there are some design considerations that can be taken into account to 
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optimize the end user experience. 



Report Dimensions and Sizing 

When a reporting application is larger than the iPad screen it becomes scrollable. A 
swiping gesture on the report allows the end user to view the off screen areas of the 
report. If the author wants the report to fit the iPad screen perfectly then the report 
should be sized to 1024 x 704 pixels. When these dimensions are used, the padding 
property of the Page Body must be explicitly set to 0, otherwise it will default to a 
value of 2 and the report will scroll. Using iPad screen sizing improves the end user 
experience because the entire report will be visible at any given time. These 
dimensions transfer well to the desktop and the report is easily consumable across 
multiple platforms. 

When creating a fixed size report it is important to plan the report layout and ensure 
that all objects and containers are sized properly. As discussed in the previous 
sections, if an object is larger than its container, the container could be pushed out 
and the entire report layout will be affected. This means that proper sizing must be 
applied to all objects and propagated throughout the entire object hierarchy in order 
to maximize screen real estate and avoid scrolling. Simply sizing the page of the 
reporting application to iPad specific dimensions will not give the desired result if the 
objects contained within the page are not properly sized. 



Scrollable Areas 

It is common practice when designing reporting applications for the desktop to nest 
large objects such as lists inside a smaller block with scrolling enabled. This 
minimizes the impact on overall screen real estate and still allows the user to view all 
of the detail contained within the object. On the desktop these scrollable areas are 
identified with scrollbars on the block. In order to remain consistent with established 
iOS navigation standards, scrollable areas on a reporting application when rendered 
in the IBM Cognos Mobile native iPad application do not have visible scrollbars. 
Furthermore, the iOS gesture to navigate these areas is a two finger scroll. This 
gesture is unintuitive to inexperienced iPad users so authors who are going to utilize 
scrollable blocks should ensure that their users are made aware of this iOS gesture. 
The following screen capture displays two lists consisting of Product line, Product 
type, Quantity, Revenue and Gross profit. The list on the left represents the desktop 
view and shows the scroll bars to the right of the Gross profit column. The list on the 
right represents the iPad view and does not have a scrollbar to the right of the Gross 
profit column. 
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Figure 32 Difference between a scrollable area on the Desktop and iPad 



Behavior on Desktop 



Behavior on iPad 





Touchable Regions 

When reporting applications are going to be used on the iPad it is important to 
remember that items that are easily selectable by a mouse on the desktop may be 
difficult to press on a touch interface. This is not a concern with standard IBM 
Cognos Active Report controls as they conform to Apple’s Human Interface 
Guidelines but is important when implementing objects such as maps. On the iPad, 
a small area on the map may be difficult for a user to select so an alternative control 
should also be provided. A simple solution is to create a control such as a drop down 
list that has the same selection options as the map in order to provide users with the 
flexibility of using either the map or the list to drive their interactions. 

Swipe Gesture 

In order to create a user experience that takes advantage of standard touch 
interface interactions, the swiping gesture can be implemented on Decks or Data 
Decks. This functionality is complemented by the Iterator control, which can be 
configured to appear as page dots to indicate the current selection. The following 
high-level procedure can be followed to enable swiping and obtain the 
corresponding page indicator dot look and feel for the Iterator control: 



• Ensure that the Iterator and the Deck are driven by the same values 

• Create a variable to be used to control the selection 

• Configure the Interactive Behaviour of both the Iterator and the Deck so 
that each control sets (Set Variable Values) and is selected by (Container 
Select) the same variable 

• Enable the desired Slide Animation Direction effect on the Deck 

• For the Iterator control, ensure that the Iterator First, Iterator Previous, 
Iterator Next and Iterator Last properties are set to Hide. Only the Iterator 
Label Area should be set to Show. 
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• Select the Iterator Label Area on the canvas and set the Select Ul 
property to Page Dots Indicator 

The detailed step by step instructions for creating a swipeable Data Deck that shows 
the historical revenue for each Product line in a separate line chart is shown below: 



1 . Within IBM Cognos Report Studio, create a new Blank Active Report. 

2. From the available Toolbox items, drag a Data Deck object onto the 
report canvas. 

3. Click on the Data Deck and within the bottom left hand Properties pane, 
change the Name property within the Miscellaneous section to 
ProductLine_Data_Deck and change the Slide Animation Direction 
property within the General section to Auto Horizontal. 

4. Within the Query Explorer tab, click on Queryl . Within the bottom left 
hand Properties pane, locate the Miscellaneous section and change the 
name of the query from Queryl to Swipe_Deck_Query. 

5. Using the Page Explorer tab, return to the report view by clicking on 
Pagel. 

6. From the available Toolbox items, hold the right mouse button and drag 
the Data Iterator object onto the report canvas and place the control 
under the Data Deck. 

7. After releasing the right mouse button, a menu appears. Select the option 
Insert using existing query. 

8. When prompted for a query, select Swipe_Deck_Query and press the OK 
button. 

9. Click on the Data Iterator and within the bottom left hand Properties pane 
change the Name property within the Miscellaneous section to 
ProductLine_Data_lterator. 

10. Within the bottom left hand Properties pane, locate the General section 
and set: 



Iterator First to Hide 
Iterator Previous to Hide 
Iterator Label Area to Show 
Iterator Next to Hide 
Iterator Last to Hide 
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1 1 . Click on the Label area of the Data Iterator in the report canvas and within 
the bottom left hand Properties pane under the General section, change 
the Select Ul property to Page Dots Indicator. 

12. Using the available source items, populate the ProductLine_Data_lterator 
Label drop zone with the GO Sales(query)\Sales(query)\Products\Product 
line. 

13. From the available Data Items drag Product line from the 
Swipe_Deck_Query into the Values drop zone of the 
ProductLine_Data_Deck. 

1 4. From the available Toolbox items, locate the Chart object and drag it into 
the Data Deck named ProductLine_Data_Deck. 

1 5. Within the Insert Chart dialog box, select line chart and press the OK 
button. 

1 6. Click on the Chart and within the bottom left hand Properties pane change 
the Name property within the Miscellaneous section to 
ProductLine_Chart. 

1 7. Using the available source items, populate the Line Chart object with the 
GO Sales(query)\Sales(query)\Products\Product line on the Series, the 
GO Sales(query)\Sales(query)\Time\Year as the Categories and GO 
Sales(query)\Sales(query)\Sales\Revenue as the measure. 

1 8. Within the Query Explorer tab, click on Queryl . Within the bottom left 
hand Properties pane, locate the Miscellaneous section and change the 
name of the query from Queryl to Chart_Query. 

1 9. Using the Page Explorer tab, return to the report view by clicking on 
Pagel. 

20. Select the Chart object and within the left hand Properties pane under the 
Data section, select the Master Detail Relationships property by clicking 
the ellipsis. 

21 . Within the Master Detail Relationships dialog box, define a relationship 
between the Swipe_Deck_Query and the Chart_Query by clicking the 
New Link. This should link Swipe_Deck_Query \ Product line to 
Chart_Query \ Product line. 

22. Click the OK button to commit the relationship and return back to the 
report page. 
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23. Click the Interactive Behavior icon to the right of the Data Deck. 

24. Double click on the Set Variable Values area of the Interactive Behavior 
dialog box. 

25. Select the Create a New Variable link and create a variable named 
varProductLine with a Data Type of String and a default value of 
‘Camping Equipment’. Click OK to return to the Set Variable Values dialog 
box. 

26. For varProductLine, change the Value field from Do not set to Product line 
and click OK to return to the Interactive Behavior dialog box. 

27. Double click on the Container Select area and select the Data Item radio 
button from the Item area on the left hand side of the dialog box. Ensure 
that Product line is selected from the drop-down menu. 

28. Set the value in the Operator drop-down menu to IN. 

29. Select the Active Report Variable radio button from the Item area on the 
right hand side of the dialog box and ensure that varProductLine is 
selected from the drop down menu. 

30. Cick OK three times to commit the modifications to the Data Deck’s 
interactive behaviour. 

31 . Click the Interactive Behavior icon to the right of the Data Iterator. 

32. Double click on the Set Variable Values area of the Interactive Behavior 
dialog box. 

33. For varProductLine, change the Value field from Do not set to Product line 
and click OK to return to the Interactive Behavior dialog box. 

34. Double click on the Container Select area and select the Data Item radio 
button from the Item area on the left hand side of the dialog box. Ensure 
that Product line is selected from the drop-down menu. 

35. Set the value in the Operator drop-down menu to IN. 

36. Select the Active Report Variable radio button from the Item area on the 
right hand side of the dialog box and ensure that varProductLine is 
selected from the drop down menu. 

37. Click OK three times to commit the modifications to the Data Iterator’s 
interactive behaviour. 
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38. If this IBM Cognos Active Report is executed, it will display a line chart for 
the revenue of Camping Equipment. The Data Iterator will appear as 
Page Dots Indicator below the chart. In the desktop browser, clicking on 
the various page dots will change the chart. When this same report is 
consumed in the IBM Cognos Mobile native iPad application, the user can 
use the swipe gesture on the chart to transition to the next chart. 



Common IBM Cognos Active Report Functionality 

The flexibility of IBM Cognos Active Report controls allows a wide variety of 
functionality to be implemented. The following sections will present commonly used 
techniques that leverage standard controls to deliver compelling end user 
experiences. IBM Cognos Active Report outputs that demonstrate the functionality 
and the corresponding report specifications are included in ARFunctionality.zip. The 
report specifications are built from the GO Sales dataset and the GO Sales (query) 
package so IBM Cognos customers can open and fully interact with the reports in 
IBM Cognos Report Studio. 

Default Cards 

When the variable that controls the selection of a Deck is empty or does not match a 
card name then a default card can be used to show content to the user. This is 
useful for displaying summary information to the user before they make a valid 
selection. Changing the Default Card property in a Deck’s property panel to Yes will 
enable the default card. When this feature is enabled a new No Data Contents icon 
appears above the Deck. The author can select this icon to view the default card and 
add report objects. 

Making Use of the No Value List Item 

When working with a List or Drop-Down List an additional item can be added to the 
list. The author has control over the text that is shown and when it is selected the 
variable that is set by the list is cleared. This functionality can be used to accomplish 
several design goals. For example, if list selection is being used to filter an object 
then the extra item can be labelled Show All and when it is selected all filters will be 
removed. Additionally, it could be used to select a default card in a deck. To enable 
this functionality select the List or Drop-Down List and change the No Value List Item 
to Show. 

Calculating Summaries in the Output 

When the end user dynamically filters a List or Crosstab, the Summarize in Output 
functionality can be used to aggregate the data that is currently being shown in the 
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filtered object. The supported aggregation methods are total, count, average, 
minimum and maximum. This functionality can be accessed through the Summarize 
menu on the IBM Cognos Report Studio toolbar. This feature will ensure that the 
correct summary information is always presented to the end user as they interact 
with a List or Crosstab. 

Clickable Regions 

There are multiple areas of objects that can be used to drive interactivity. The 
Clickable Regions property can be used to set which areas of each object are 
selectable. The menu will adjust to reflect the correct options for each object. 

Showing and Hiding List Columns or Crosstab Columns and Rows 

The visibility of list columns can be controlled by variables. The Column Visibility 
menu that is accessible in the List Column Body Properties panel allows the author 
to set the visibility based on a condition. A multi-select control such as a Check Box 
Group can be used to control which columns in the list are visible. This allows the 
end user to show only the information that they are interested in on the screen. The 
same concept can be applied to hiding and showing crosstab rows and columns. 
This crosstab functionality can be accessed in the Container Filter menu of the 
Crosstab Properties panel. This functionality is demonstrated in the supporting file 
Toggled List Column Display.mht. 

Sorting List Columns 

List column sorting can be enabled by selecting the appropriate column and 
changing the Allow Sorting property to Yes. This will allow the user to toggle sorting 
on or off and enables sorting in both ascending and descending order. 

Drilling Through to a Live Report 

Drill-through can be used to provide the end user with access to more details on 
demand while they are connected. This functionality allows summary level 
dashboards to be built without sacrificing the ability to get to more detail when 
required. To ensure that context is not lost while drilling through, parameter values 
or data item values can be used to populate prompts in the target report. In order to 
setup a drill-through, the Drill-Through Definitions menu in the Properties panel for 
report objects can be used. 

Expandable and Collapsible Regions 

To save screen real estate the report author can choose to hide areas of a reporting 
application. This type of functionality can be particularly useful for showing or hiding 
filter criteria or additional metrics that are not frequently used. To accomplish this an 
author can include the information they want to hide on a card of a Deck and create 
an empty card in the same Deck. A variable can be used to determine whether the 
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card with content or the blank card should be shown. When the blank card is active, 
the content will not be visible and objects beside the Deck will collapse into its 
location. When the variable is changed to select the card with content, the layout will 
adjust to reveal the additional detail. This functionality is demonstrated in the 
supporting file Hidden Report Regions. mht. 



Disabling Until a Condition is Met 

An author can disable the use of controls or hide content from the end user until a 
condition is met. This is useful for when additional functionality or detail will only be 
shown if a particular item is selected. To disable the use of a control based on a 
condition the Control Enable functionality in the Interactive Behaviour menu can be 
used. To hide content until a condition is satisfied, a Deck with an empty default card 
can be used. Alternatively, the default card can be used to provide a cue to the end 
user that more information is available if they make the proper selection. This 
functionality is demonstrated in the supporting file Disabling Until a Condition is 
Met. mht. 



Creating Custom Content Buttons 

The IBM Cognos Active Report Button control provides the author with a simple way 
to implement a standard look and feel button. For some applications the author may 
choose to create a button with a customized look and feel. To accomplish this, a List 
object can be used. In order to create a single button, a single cell list is created. 
This is done by including a single data item in a list and then selecting the List 
Column Title and setting the Box Type property to None. The cell can then be styled 
with a background colour or image to create the desired look and feel. Arrays of 
buttons can be constructed by including this functionality in a Repeater Table. This 
functionality is demonstrated in the supporting files Custom Buttons. mht and 
Repeaters and Buttons, mht. 



Cascading Prompt Controls 

Cascading prompts are useful for interacting with a reporting application when there 
is hierarchical data. Cascading prompts allow the end user to progressively filter 
their data in an intuitive way instead of presenting a long list of items and forcing the 
user to search for their desired selection. To build a cascading prompt, each control 
must be filtered by the selections made in all of the higher-level controls. In order to 
accomplish this, all of the higher-level items must be included in the Values section 
of each control so that they are present in the control’s query. The author can also 
choose whether or not they want to allow the user to immediately select a value from 
the lowest level prompt or whether they want to force a selection in all controls. If the 
author wants to force selection, then the Control Enable functionality can be used. 
Alternatively, the author can hide lower level prompt controls and enable progressive 
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disclosure by putting all of the lower-level controls into their own Decks. The default 
card functionality can then be used to choose when to reveal the control to the end 
user. Using this technique, animation can be enabled on the Decks to make it 
appear to the end user like the new controls are sliding into view after a selection is 
made. This functionality is demonstrated in the supporting files Cascading 
Prompt. mht and Cascading Animated Prompt. mht. 



Tree Control 

An alternative to the cascading prompt that provides similar functionality and 
benefits for efficiently making hierarchical selections is the tree control. The tree 
control makes use of lists to display each section of selection options. The various 
levels of the selection hierarchy are contained in separate Decks and variables are 
used to filter the display Lists and show or hide Decks to provide the desired 
functionality. This functionality is demonstrated in the supporting file Tree 
Control, mht. 



Creating a Scrolling Key Metrics Area 

The focal point of many dashboards is a key metrics area that provides the business 
user with a high level view of their key performance indicators. In IBM Cognos Active 
Report, these metric areas can be updated based on user selection. To accomplish 
this functionality, the metrics area should be built in a Data Deck that is driven by the 
same item as the selection control. To get the proper values to show up, a Text Item 
should be used with the Source Type set to Data Item Value. The Data Item Value 
property should then be set to the measure that will be displayed. In order for the 
measure to appear as an option in the Data Item Value property it must be included 
in the query that the Data Deck is using. This functionality is demonstrated in the 
supporting file Top Metrics. mht. 



User Toggled Conditional Styling 

Conditional styling is used to highlight areas of interest within a report object. By 
providing the end user with the flexibility to control the criteria of the conditional 
styling, they can quickly navigate between different visual indicators of performance. 
For example, the user can choose whether they want the best or worst performers 
highlighted. To accomplish this, the report object should be duplicated on multiple 
Cards in a Deck. Different conditional styling should then be applied to the objects 
on each Card. The title of each Card should reflect the conditional styling that is 
present on that Card. A selection control should then be connected to the Deck that 
allows the user to select the conditional styling they want to view. This functionality is 
demonstrated in the supporting file Toggled Conditional Styling. mht. 
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Sliding to Visualize Deltas Over Time 

To gain an understanding of how information within a chart is changing over time a 
Discrete Value Slider can be used to update the chart. To implement this 
functionality the chart should be placed in a Data Deck that is driven by the desired 
time period. Once the proper Master Detail Relationship is setup a Data Discrete 
Value Slider can be connected to the Data Deck to control the selection. If the 
Update Variables Live property of the Data Discrete Values Slider is set to Yes then 
the chart will update as the slider is dragged. This functionality is demonstrated in 
the supporting file Sliding to Visualize Changes. mht. 



Drilling Down to Details 

End users often want access to additional detail and in order for this to be made 
available offline, a drill down must be authored into the reporting application. The 
different levels of detail need to be included in separate Decks or Data Decks. When 
a selection is made and a user wants to drill down, variables and Default Card 
functionality is used to hide the current Deck and reveal the Deck that contains the 
lower-level information. An advantage of this approach is that the data can be 
represented in a different form at each level. For example, Product Line Revenue 
can be shown in a list and when the user drills into Product Line, the Product Type 
Revenue could be shown against the planned values in a Bullet Chart. In order to 
allow the user to navigate back up the drill path a breadcrumb trail should be left. 
This can be made of a variety of controls that set the variables such that the user is 
returned to the desired level of detail. This functionality is demonstrated in the 
supporting file Drill to Details. mht. 



Scrollable Selection Controls 

List Box, Check Box Group and Radio Button Group controls can become large if 
they contain many selection options. In order to save screen real estate an author 
can enable scrolling so that only a portion of the selections are visible at any given 
time. The List Box automatically becomes scrollable when the contents are larger 
than its size. This does not occur for the Check Box Group and Radio Button Group 
controls. In order to enable scrolling on these controls they should be placed inside a 
fixed sixed block with Overflow property set to use scrollbars only when necessary. 
The Overflow property can be found inside the Size & Overflow Property dialogue 
box. This functionality is demonstrated in the supporting file Scrollable Control 
List. mht. 



Clickable Exploding Pie Slices 

The exploding pie slice functionality is useful for providing a visual indication of 
selection. It also increases the level of interactivity on the pie chart and improves the 
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end user experience. To accomplish this functionality, the pie chart must be placed 
into a Data Deck that is driven by the same item as the Pie Chart Series in order to 
generate a unique version of the chart for every possible exploded slice. The Pie 
Chart and Data Deck must also use different queries. To ensure that the correct 
slice is exploded when it is selected, a selection connection must be setup between 
the Pie Chart and the Data Deck. Additionally, the Exploded Slices property of the 
Pie Chart must be setup to use an expression such that [Pie Chart Query], [Pie Chart 
Series Item] = [Data Deck Query], [Pie Chart Series Item], This functionality is 
demonstrated in the supporting file Exploding Pie Slice. mht. 



Scrolling Marquee of Data 

The scrolling marquee can be used to passively display key metrics or information 
that will continually scroll across the screen. This gives the end user a stock ticker 
like experience. In order to accomplish this, the desired string should be built within 
a Repeater control. The string can be built by using multiple Text Item controls that 
use Text, Data Item Value or Data Item Label as the Source Type. The Repeater 
should then be placed in a fixed sized Block with an HTML Item. The HTML in the 
HTML Item should be ‘<marquee>’ and the Block Overflow should be set to content 
is clipped. This functionality is demonstrated in the supporting file Scrolling 
Marquee. mht. 



Embedded Videos 

Reporting applications can display video content for the end user. This functionality 
is enabled with an HTML Item. The HTML Item describes the size of the frame that 
will display the video and the source of the video. A user must be connected in order 
to consume a video. This functionality is demonstrated in the supporting file 
Embedded Videos, mht. 



Absolutely Positioning Content 

When a dashboard is built using fixed sizing it is possible to overlay additional report 
objects. For example, when selecting different regions on a map, a chart that 
provides additional details can be overlaid on that location. In order to accomplish 
this, HTML Items that describe the absolute pixel location of the object are used. 

The HTML sets the base location of the object and then based on selections made 
in the reporting application; the HTML can offset the location of the object to make it 
appear in the proper location. This functionality is demonstrated in the supporting file 
Absolutely Positioned Content.mht. 
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Creating an IBM Cognos Active Report Dashboard 

The following sections will step a user through the process that should be followed 
when designing an IBM Cognos Active Report. A basic example will be presented to 
illustrate the workflow. 



The Use-Case 

Ed, the Vice President of Sales for the Great Outdoors Company, is responsible for 
expanding the company’s market share globally. Ed closely monitors the revenue 
that is generated through the company’s main sales channels and directly oversees 
a team of Territory Managers that are responsible for regional growth. He spends 
most of his time travelling and meeting with key customers. While on the road, Ed 
needs to be able to monitor the performance of his sales organization to ensure that 
the company is meeting their growth targets. He has increasingly been using his 
iPad for all of his communication needs, especially while travelling. Ed needs access 
to enough detail so that he can identify areas of concern and delegate further 
analysis to his management team. 



Identify Requirements and Choose a Technology 

After receiving the use-case, the author must now evaluate the key requirements of 
the dashboard and pick the IBM Cognos technology that will be best suited to 
solving the business problem. When evaluating IBM Cognos Active Report as a 
potential solution, the use-case should be evaluated against the key features of the 
solution in order to ensure a successful deployment. The key aspects of this 
particular scenario are: 



• Business Problem: The VP of Sales needs to be able to monitor the 
company’s performance against their targets. Ed needs to be able to 
quickly identify any emerging trends that could negatively impact the 
revenue of the company and take corrective action before it is too late. 

• Key Features of the Solution: 

• Summary Level: Ed is responsible for global sales and requires 
summary level data. Ed does not drive his own analysis. He instead 
chooses to delegate this work to Territory Managers. 

• Portable: Ed spends most of his time travelling which means he will 
need to be able to access his Bl information from his mobile device. 
Additionally, Ed may not have access to a consistent network 
connection so the ability to consume content offline is important. 
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In this situation, the requirements for a portable and disconnected solution make 
IBM Cognos Active Report an ideal solution. Additionally, since Ed deals with 
summary level data, all of the information that he requires on a daily basis can be 
included in a single high performance reporting application. 



Designing the Dashboard 

In order to simplify the overall dashboard creation process, the author should 
carefully plan out the design of the dashboard before beginning the assembly. 



Identifying the Information Needed to Solve the Business Problem 

With IBM Cognos Active Report identified as the proper technology, the author must 
now determine what information needs to be included in the dashboard to solve the 
business problem. Only information that will be used on a daily basis should be 
included in the reporting application. Additional detailed data that will not routinely be 
accessed should be authored into a separate report that will be a drill-through target 
from the high level dashboard. This will prevent the reporting application from 
becoming unnecessarily large. 

Another factor to consider is the time sensitivity of the data and how it relates to the 
use-case and deployment scenario. For example, if the dashboard will be scheduled 
so that Ed receives a fresh version every Monday but it is known that he often tracks 
closed deals on a daily basis, then the closed deals information should be made 
accessible with a drill-through so that he always gets the freshest information when 
he accesses that portion of the report. 



Determining the Layout 

The first decision that needs to be made is what layout strategy will be used for the 
reporting application. This requirement should be driven by the use-case. For 
example, if the use-case is iPad centric then the layout should be a fixed size of 
1024 x 704 to provide the best user experience. If the use-case is broad distribution 
for predominately desktop consumption then using a layout that uses relative sizing 
may be prudent. It is likely that this will create a reporting application that requires 
scrolling to reveal off-screen content on the iPad, but the experience on desktop 
monitors will be optimized. The author must make this decision with careful 
consideration of the requirements because it will impact the end user experience. In 
this specific scenario, the end user is often travelling so the iPad specific sizing will 
be used as the layout strategy. 



Before beginning the construction of the dashboard it is recommended that the 
author create sketches of the layout to better understand the overall functionality of 
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the dashboard. A proposed layout for the dashboard is shown in the image below. 
This dashboard highlights Ed’s main areas of interest, sales by territory, 
performance against plan and sales by channel. As is the case with this dashboard, 
individual analysis areas are often separated into discrete sections for easy 
navigation. This layout uses a button bar at the top of the dashboard to navigate 
between the two main sections of the report, Sales Overview and Channel Analysis. 



The interactivity in the Sales Overview section is driven by an exploding pie chart in 
the top left corner. The pie chart shows the revenue breakdown by product line and 
when the end user selects a slice of the pie, the rest of the content updates to show 
additional detail about the selected product line. The key metrics area that is directly 
below the pie chart provides the user with high-level information including revenue, 
planned revenue, quantity and gross profit for the selected product line. Upon 
selection, the metrics area will scroll vertically to provide the user with a visual cue 
that the data has updated. Conditional formatting will also be used to draw the end 
users attention to areas of concern. Two additional graphs are stacked vertically to 
the right of the pie chart and show a time series and a geographic comparison of 
actual revenue versus planned revenue for the selected product line. 



The Channel Analysis section consists of a summary level list that covers the top 
half of the dashboard with more detailed charts below that update based on the 
channel that the user selects in the list. The list will include a spark line chart for 
quarter-over-quarter revenue and a bullet chart to show the performance versus plan 
for channel revenue. Additional data in the list will include unit cost, unit price, 
revenue, planned revenue and gross profit. The detailed charts will show a 
geographic comparison of planned versus actual revenue and a time series of 
revenue by product line for the selected channel. The charts at the bottom can be 
navigated on the iPad with a swipe gesture and the channel that is currently being 
shown will be highlighted in the list. The Iterator control with Page Dot Indicators will 
be placed below the charts to provide a visual cue that swiping is enabled. 
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Figure 33 Proposed layout of the IBM Cognos Active Report dashboard 
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The dashboard proposal should now be communicated with key stakeholders to 
align on the content, layout and level of detail. The authoring effort will be 
significantly reduced if the core functionality is agreed upon before design iterations 
begin. 



Building the Dashboard 

Once the desired layout and functionality is finalized, the construction of the 
dashboard can begin. The construction of the dashboard can be segmented into 
several steps. 



Build the layout and add controls 

The first thing to consider when beginning a layout is where Decks are going to be 
used and what interactivity they will provide. For example, in this scenario a button 
bar is being used to navigate between the main sections so a Deck will need to be 
used to support this functionality. A standard Deck will be used because it is known 
that there are two unique sections, each of which will be built on its own Card. As 
shown in the image below, on the Sales Overview Card there are three separate 
Data Decks that are needed to achieve the desired functionality. All three Decks will 
be Data Decks because they all need to provide a unique view for each member of 
Product Line. 



• Pie Chart Deck: This deck contains only the pie chart and its purpose is to 
enable the exploding slice functionality that shows which product line is 
currently selected. No animation will be enabled on this deck so to the 
end user it will appear that the slice they select instantly pops out. 



• Metrics Deck: This Data Deck holds the numeric values in the key metrics 
area. It is in a separate deck because vertical animation will be used on 
this portion of the report to provide a visual indication that the content has 
updated. The titles of the metrics are not included in the Data Deck in 
order to prevent the titles from animating on selection. 



• Detailed Charts Deck: This Data Deck includes the detailed charts to the 
right of the pie chart. They are in a separate Data Deck in order to 
accomplish the desired report layout. Animation will not be enabled on 
this Deck so it will appear that these charts update in place. 
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Figure 34 Deck layout for the Sales Overview Card 
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For the Channel Analysis Card only one additional deck is required. As shown in the 
image below, a Data Deck is required for the detailed charts that are below the 
summary list. A Data Deck is used because unique content is required for each 
member of Sales Channel. Auto Horizontal animation will be enabled on this deck to 
support the iPad swiping functionality. 



Figure 35 Deck layout for the Channel Analysis Card 
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With the required Decks finalized, the report layout can now be constructed. In order 
to achieve the desired layout, Tables and Blocks should be used. In this scenario, 
Tables will be used because they are more flexible and this dashboard does not 
require any scrollable areas. As shown in the image below, the first step of laying out 
the report is to create a table that divides the dashboard into its main sections. In 
this case, it is a Table with three rows and one column. The first row will hold the title 
text, the second row contains the Button Bar that selects the visible section and the 
third row will hold the Deck that contains each main section on a Card. 



Figure 36 The main dashboard layout Table 
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The content of each main section can now be laid out on their own Cards in the 
Deck. In order to create the desired layout, it will be necessary to nest Tables inside 
of Decks or Table Cells. As shown in the image below, the detailed charts on the 
right side of the Sales Overview Card can be placed by first dividing the Card into 
two columns and one row with a Table. The right column can then be populated with 
a Data Deck to support the desired interactivity. This Data Deck will have a Table 
with two rows and one column placed on its Card. A chart will be placed in each 
Table Cell, which will allow the orientation of the detailed charts to be fixed. This 
process can be used to place the remaining objects required on the dashboard. 



Figure 37 The layout of the detailed charts on the Sales Overview Card 
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Set up the functionality 

Once the objects and controls are properly placed, the interactivity can be authored 
into the reporting application. The authoring guidelines and best practices that were 
presented throughout this document should be utilized when building out and testing 
the interactivity. 

After the desired interactivity is achieved, the dashboard should again be socialized 
with stakeholders. 
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Apply appropriate sizing 

After the layout and functionality is completed, fixed sizing should be applied to the 
objects in the dashboard in order to ensure that the reporting application fits the iPad 
screen. With an overall reporting application size of 1024 x 704 pixels, the individual 
object sizes all need to be determined so that the usage of screen real estate can be 
optimized. Sizing should be applied to both the objects and their containers. It is also 
important to consider spacing while doing this exercise. For example, the detailed 
chart section of the Sales Overview Card could be sized so that each chart is 350 x 
200 pixels and the table cells that contain each chart are 375 x 225 pixels. The 
charts can then be centre and middle aligned in the Table Cells to provide 
appropriate spacing between the objects. The Deck that holds these objects would 
then need to be sized to match the Table within it, which would have a total size of 
375 x 450 because the charts are arranged vertically. The size of this Deck then 
propagates upwards to drive the size of its container and this process continues until 
all objects and containers are properly sized. 

Before beginning to size objects it is useful to return to the original sketches of the 
dashboard and apply rough sizing to all objects. This will ensure that all of the sizes 
will sum to the correct value and screen real estate decisions can be made before 
the sizing has been hardcoded into the reporting application. 



Styling the dashboard 

Styling of the dashboard should be the last task when creating an IBM Cognos 
Active Report. A consistent look and feel should be applied to all controls, data, 
layout objects, images, icons and text. Classes, Templates and Layout Component 
Reference objects should be used for a number of reasons. These objects will 
reduce the time required to apply and adjust styling and will also provide a library of 
design styles that can be reused for other reports. Classes also have an additional 
benefit, if used they reduce the size of the MHT output file, which will improve 
transfer time across networks and load times in the browser or IBM Cognos Mobile 
iPad application. 
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